home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / plugin.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  14KB  |  521 lines
  1. /**
  2.  * @file plugin.h Plugin API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_PLUGIN_H_
  26. #define _GAIM_PLUGIN_H_
  27.  
  28. #include <glib/glist.h>
  29. #include <gmodule.h>
  30. #include "signals.h"
  31. #include "value.h"
  32.  
  33. typedef struct _GaimPlugin           GaimPlugin;
  34. typedef struct _GaimPluginInfo       GaimPluginInfo;
  35. typedef struct _GaimPluginUiInfo     GaimPluginUiInfo;
  36. typedef struct _GaimPluginLoaderInfo GaimPluginLoaderInfo;
  37.  
  38. typedef struct _GaimPluginAction     GaimPluginAction;
  39.  
  40. typedef int GaimPluginPriority; /**< Plugin priority. */
  41.  
  42. #include "pluginpref.h"
  43.  
  44. /**
  45.  * Plugin types.
  46.  */
  47. typedef enum
  48. {
  49.     GAIM_PLUGIN_UNKNOWN  = -1,  /**< Unknown type.    */
  50.     GAIM_PLUGIN_STANDARD = 0,   /**< Standard plugin. */
  51.     GAIM_PLUGIN_LOADER,         /**< Loader plugin.   */
  52.     GAIM_PLUGIN_PROTOCOL        /**< Protocol plugin. */
  53.  
  54. } GaimPluginType;
  55.  
  56. #define GAIM_PRIORITY_DEFAULT     0
  57. #define GAIM_PRIORITY_HIGHEST  9999
  58. #define GAIM_PRIORITY_LOWEST  -9999
  59.  
  60. #define GAIM_PLUGIN_FLAG_INVISIBLE 0x01
  61.  
  62. #define GAIM_PLUGIN_MAGIC 5 /* once we hit 6.0.0, I think we can remove this */
  63.  
  64. /**
  65.  * Detailed information about a plugin.
  66.  *
  67.  * This is used in the version 2.0 API and up.
  68.  */
  69. struct _GaimPluginInfo
  70. {
  71.     unsigned int magic;
  72.     unsigned int major_version;
  73.     unsigned int minor_version;
  74.     GaimPluginType type;
  75.     char *ui_requirement;
  76.     unsigned long flags;
  77.     GList *dependencies;
  78.     GaimPluginPriority priority;
  79.  
  80.     char *id;
  81.     char *name;
  82.     char *version;
  83.     char *summary;
  84.     char *description;
  85.     char *author;
  86.     char *homepage;
  87.  
  88.     gboolean (*load)(GaimPlugin *plugin);
  89.     gboolean (*unload)(GaimPlugin *plugin);
  90.     void (*destroy)(GaimPlugin *plugin);
  91.  
  92.     void *ui_info;
  93.     void *extra_info;
  94.     GaimPluginUiInfo *prefs_info;
  95.     GList *(*actions)(GaimPlugin *plugin, gpointer context);
  96. };
  97.  
  98. /**
  99.  * Extra information for loader plugins.
  100.  */
  101. struct _GaimPluginLoaderInfo
  102. {
  103.     GList *exts;
  104.  
  105.     gboolean (*probe)(GaimPlugin *plugin);
  106.     gboolean (*load)(GaimPlugin *plugin);
  107.     gboolean (*unload)(GaimPlugin *plugin);
  108.     void     (*destroy)(GaimPlugin *plugin);
  109. };
  110.  
  111. /**
  112.  * A plugin handle.
  113.  */
  114. struct _GaimPlugin
  115. {
  116.     gboolean native_plugin;                /**< Native C plugin.          */
  117.     gboolean loaded;                       /**< The loaded state.         */
  118.     void *handle;                          /**< The module handle.        */
  119.     char *path;                            /**< The path to the plugin.   */
  120.     GaimPluginInfo *info;                  /**< The plugin information.   */
  121.     char *error;
  122.     void *ipc_data;                        /**< IPC data.                 */
  123.     void *extra;                           /**< Plugin-specific data.     */
  124. };
  125.  
  126. #define GAIM_PLUGIN_LOADER_INFO(plugin) \
  127.     ((GaimPluginLoaderInfo *)(plugin)->info->extra_info)
  128.  
  129. struct _GaimPluginUiInfo {
  130.     GaimPluginPrefFrame *(*get_plugin_pref_frame)(GaimPlugin *plugin);
  131.  
  132.     void *iter;                                           /**< Reserved */
  133.     GaimPluginPrefFrame *frame;                           /**< Reserved */
  134. };
  135.  
  136. #define GAIM_PLUGIN_HAS_PREF_FRAME(plugin) \
  137.     ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
  138.  
  139. #define GAIM_PLUGIN_UI_INFO(plugin) \
  140.     ((GaimPluginUiInfo*)(plugin)->info->prefs_info)
  141.  
  142.  
  143. /**
  144.  * The structure used in the actions member of GaimPluginInfo
  145.  */
  146. struct _GaimPluginAction {
  147.     char *label;
  148.     void (*callback)(GaimPluginAction *);
  149.  
  150.     /** set to the owning plugin */
  151.     GaimPlugin *plugin;
  152.  
  153.     /** NULL for plugin actions menu, set to the GaimConnection for
  154.         account actions menu */
  155.     gpointer context;
  156. };
  157.  
  158. #define GAIM_PLUGIN_HAS_ACTIONS(plugin) \
  159.     ((plugin)->info != NULL && (plugin)->info->actions != NULL)
  160.  
  161. #define GAIM_PLUGIN_ACTIONS(plugin, context) \
  162.     (GAIM_PLUGIN_HAS_ACTIONS(plugin)? \
  163.     (plugin)->info->actions(plugin, context): NULL)
  164.  
  165.  
  166. /**
  167.  * Handles the initialization of modules.
  168.  */
  169. #if !defined(GAIM_PLUGINS) || defined(GAIM_STATIC_PRPL)
  170. # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
  171.     gboolean gaim_init_##pluginname##_plugin(void) { \
  172.         GaimPlugin *plugin = gaim_plugin_new(TRUE, NULL); \
  173.         plugin->info = &(plugininfo); \
  174.         initfunc((plugin)); \
  175.         return gaim_plugin_register(plugin); \
  176.     }
  177. #else /* GAIM_PLUGINS  && !GAIM_STATIC_PRPL */
  178. # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
  179.     G_MODULE_EXPORT gboolean gaim_init_plugin(GaimPlugin *plugin) { \
  180.         plugin->info = &(plugininfo); \
  181.         initfunc((plugin)); \
  182.         return gaim_plugin_register(plugin); \
  183.     }
  184. #endif
  185.  
  186.  
  187. #ifdef __cplusplus
  188. extern "C" {
  189. #endif
  190.  
  191.  
  192. void *gaim_plugins_get_handle(void);
  193.  
  194.  
  195. /**************************************************************************/
  196. /** @name Plugin API                                                      */
  197. /**************************************************************************/
  198. /*@{*/
  199.  
  200. /**
  201.  * Creates a new plugin structure.
  202.  *
  203.  * @param native Whether or not the plugin is native.
  204.  * @param path   The path to the plugin, or @c NULL if statically compiled.
  205.  *
  206.  * @return A new GaimPlugin structure.
  207.  */
  208. GaimPlugin *gaim_plugin_new(gboolean native, const char *path);
  209.  
  210. /**
  211.  * Probes a plugin, retrieving the information on it and adding it to the
  212.  * list of available plugins.
  213.  *
  214.  * @param filename The plugin's filename.
  215.  *
  216.  * @return The plugin handle.
  217.  *
  218.  * @see gaim_plugin_load()
  219.  * @see gaim_plugin_destroy()
  220.  */
  221. GaimPlugin *gaim_plugin_probe(const char *filename);
  222.  
  223. /**
  224.  * Registers a plugin and prepares it for loading.
  225.  *
  226.  * This shouldn't be called by anything but the internal module code.
  227.  *
  228.  * @param plugin The plugin to register.
  229.  */
  230. gboolean gaim_plugin_register(GaimPlugin *plugin);
  231.  
  232. /**
  233.  * Attempts to load a previously probed plugin.
  234.  *
  235.  * @param plugin The plugin to load.
  236.  *
  237.  * @return @c TRUE if successful, or @c FALSE otherwise.
  238.  *
  239.  * @see gaim_plugin_reload()
  240.  * @see gaim_plugin_unload()
  241.  */
  242. gboolean gaim_plugin_load(GaimPlugin *plugin);
  243.  
  244. /**
  245.  * Unloads the specified plugin.
  246.  *
  247.  * @param plugin The plugin handle.
  248.  *
  249.  * @return @c TRUE if successful, or @c FALSE otherwise.
  250.  *
  251.  * @see gaim_plugin_load()
  252.  * @see gaim_plugin_reload()
  253.  */
  254. gboolean gaim_plugin_unload(GaimPlugin *plugin);
  255.  
  256. /**
  257.  * Reloads a plugin.
  258.  *
  259.  * @param plugin The old plugin handle.
  260.  *
  261.  * @return @c TRUE if successful, or @c FALSE otherwise.
  262.  *
  263.  * @see gaim_plugin_load()
  264.  * @see gaim_plugin_unload()
  265.  */
  266. gboolean gaim_plugin_reload(GaimPlugin *plugin);
  267.  
  268. /**
  269.  * Unloads a plugin and destroys the structure from memory.
  270.  *
  271.  * @param plugin The plugin handle.
  272.  */
  273. void gaim_plugin_destroy(GaimPlugin *plugin);
  274.  
  275. /**
  276.  * Returns whether or not a plugin is currently loaded.
  277.  *
  278.  * @param plugin The plugin.
  279.  *
  280.  * @return TRUE if loaded, or FALSE otherwise.
  281.  */
  282. gboolean gaim_plugin_is_loaded(const GaimPlugin *plugin);
  283.  
  284. /*@}*/
  285.  
  286. /**************************************************************************/
  287. /** @name Plugin IPC API                                                  */
  288. /**************************************************************************/
  289. /*@{*/
  290.  
  291. /**
  292.  * Registers an IPC command in a plugin.
  293.  *
  294.  * @param plugin     The plugin to register the command with.
  295.  * @param command    The name of the command.
  296.  * @param func       The function to execute.
  297.  * @param marshal    The marshalling function.
  298.  * @param ret_value  The return value type.
  299.  * @param num_params The number of parameters.
  300.  * @param ...        The parameter types.
  301.  *
  302.  * @return TRUE if the function was registered successfully, or
  303.  *         FALSE otherwise.
  304.  */
  305. gboolean gaim_plugin_ipc_register(GaimPlugin *plugin, const char *command,
  306.                                   GaimCallback func,
  307.                                   GaimSignalMarshalFunc marshal,
  308.                                   GaimValue *ret_value, int num_params, ...);
  309.  
  310. /**
  311.  * Unregisters an IPC command in a plugin.
  312.  *
  313.  * @param plugin  The plugin to unregister the command from.
  314.  * @param command The name of the command.
  315.  */
  316. void gaim_plugin_ipc_unregister(GaimPlugin *plugin, const char *command);
  317.  
  318. /**
  319.  * Unregisters all IPC commands in a plugin.
  320.  *
  321.  * @param plugin The plugin to unregister the commands from.
  322.  */
  323. void gaim_plugin_ipc_unregister_all(GaimPlugin *plugin);
  324.  
  325. /**
  326.  * Returns a list of value types used for an IPC command.
  327.  *
  328.  * @param plugin     The plugin.
  329.  * @param command    The name of the command.
  330.  * @param ret_value  The returned return value.
  331.  * @param num_params The returned number of parameters.
  332.  * @param params     The returned list of parameters.
  333.  *
  334.  * @return TRUE if the command was found, or FALSE otherwise.
  335.  */
  336. gboolean gaim_plugin_ipc_get_params(GaimPlugin *plugin, const char *command,
  337.                                     GaimValue **ret_value, int *num_params,
  338.                                     GaimValue ***params);
  339.  
  340. /**
  341.  * Executes an IPC command.
  342.  *
  343.  * @param plugin  The plugin to execute the command on.
  344.  * @param command The name of the command.
  345.  * @param ok      TRUE if the call was successful, or FALSE otherwise.
  346.  * @param ...     The parameters to pass.
  347.  *
  348.  * @return The return value, which will be NULL if the command doesn't
  349.  *         return a value.
  350.  */
  351. void *gaim_plugin_ipc_call(GaimPlugin *plugin, const char *command,
  352.                            gboolean *ok, ...);
  353.  
  354. /*@}*/
  355.  
  356. /**************************************************************************/
  357. /** @name Plugins API                                                     */
  358. /**************************************************************************/
  359. /*@{*/
  360.  
  361. /**
  362.  * Sets the search paths for plugins.
  363.  *
  364.  * @param count The number of search paths.
  365.  * @param paths The search paths.
  366.  */
  367. void gaim_plugins_set_search_paths(size_t count, char **paths);
  368.  
  369. /**
  370.  * Unloads all loaded plugins.
  371.  */
  372. void gaim_plugins_unload_all(void);
  373.  
  374. /**
  375.  * Destroys all registered plugins.
  376.  */
  377. void gaim_plugins_destroy_all(void);
  378.  
  379. /**
  380.  * Attempts to load all the plugins in the specified preference key
  381.  * that were loaded when gaim last quit.
  382.  *
  383.  * @param key The preference key containing the list of plugins.
  384.  */
  385. void gaim_plugins_load_saved(const char *key);
  386.  
  387. /**
  388.  * Probes for plugins in the registered module paths.
  389.  *
  390.  * @param ext The extension type to probe for, or @c NULL for all.
  391.  *
  392.  * @see gaim_plugin_set_probe_path()
  393.  */
  394. void gaim_plugins_probe(const char *ext);
  395.  
  396. /**
  397.  * Returns whether or not plugin support is enabled.
  398.  *
  399.  * @return TRUE if plugin support is enabled, or FALSE otherwise.
  400.  */
  401. gboolean gaim_plugins_enabled(void);
  402.  
  403. /**
  404.  * Registers a function that will be called when probing is finished.
  405.  *
  406.  * @param func The callback function.
  407.  * @param data Data to pass to the callback.
  408.  */
  409. void gaim_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
  410.  
  411. /**
  412.  * Unregisters a function that would be called when probing is finished.
  413.  *
  414.  * @param func The callback function.
  415.  */
  416. void gaim_plugins_unregister_probe_notify_cb(void (*func)(void *));
  417.  
  418. /**
  419.  * Registers a function that will be called when a plugin is loaded.
  420.  *
  421.  * @param func The callback function.
  422.  * @param data Data to pass to the callback.
  423.  */
  424. void gaim_plugins_register_load_notify_cb(void (*func)(GaimPlugin *, void *),
  425.                                           void *data);
  426.  
  427. /**
  428.  * Unregisters a function that would be called when a plugin is loaded.
  429.  *
  430.  * @param func The callback function.
  431.  */
  432. void gaim_plugins_unregister_load_notify_cb(void (*func)(GaimPlugin *, void *));
  433.  
  434. /**
  435.  * Registers a function that will be called when a plugin is unloaded.
  436.  *
  437.  * @param func The callback function.
  438.  * @param data Data to pass to the callback.
  439.  */
  440. void gaim_plugins_register_unload_notify_cb(void (*func)(GaimPlugin *, void *),
  441.                                             void *data);
  442.  
  443. /**
  444.  * Unregisters a function that would be called when a plugin is unloaded.
  445.  *
  446.  * @param func The callback function.
  447.  */
  448. void gaim_plugins_unregister_unload_notify_cb(void (*func)(GaimPlugin *,
  449.                                                            void *));
  450.  
  451. /**
  452.  * Finds a plugin with the specified name.
  453.  *
  454.  * @param name The plugin name.
  455.  *
  456.  * @return The plugin if found, or @c NULL if not found.
  457.  */
  458. GaimPlugin *gaim_plugins_find_with_name(const char *name);
  459.  
  460. /**
  461.  * Finds a plugin with the specified filename (filename with a path).
  462.  *
  463.  * @param filename The plugin filename.
  464.  *
  465.  * @return The plugin if found, or @c NULL if not found.
  466.  */
  467. GaimPlugin *gaim_plugins_find_with_filename(const char *filename);
  468.  
  469. /**
  470.  * Finds a plugin with the specified basename (filename without a path).
  471.  *
  472.  * @param basename The plugin basename.
  473.  *
  474.  * @return The plugin if found, or @c NULL if not found.
  475.  */
  476. GaimPlugin *gaim_plugins_find_with_basename(const char *basename);
  477.  
  478. /**
  479.  * Finds a plugin with the specified plugin ID.
  480.  *
  481.  * @param id The plugin ID.
  482.  *
  483.  * @return The plugin if found, or @c NULL if not found.
  484.  */
  485. GaimPlugin *gaim_plugins_find_with_id(const char *id);
  486.  
  487. /**
  488.  * Returns a list of all loaded plugins.
  489.  *
  490.  * @return A list of all loaded plugins.
  491.  */
  492. GList *gaim_plugins_get_loaded(void);
  493.  
  494. /**
  495.  * Returns a list of all protocol plugins.
  496.  *
  497.  * @return A list of all protocol plugins.
  498.  */
  499. GList *gaim_plugins_get_protocols(void);
  500.  
  501. /**
  502.  * Returns a list of all plugins, whether loaded or not.
  503.  *
  504.  * @return A list of all plugins.
  505.  */
  506. GList *gaim_plugins_get_all(void);
  507.  
  508. /*@}*/
  509.  
  510.  
  511. /**
  512.  * Allocates and returns a new GaimPluginAction.
  513.  */
  514. GaimPluginAction *gaim_plugin_action_new(char* label, void (*callback)(GaimPluginAction *));
  515.  
  516. #ifdef __cplusplus
  517. }
  518. #endif
  519.  
  520. #endif /* _GAIM_PLUGIN_H_ */
  521.